home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1993…ch: Other People's Memory / ADC Developer CD (1993-03) (''Other People's Memory'')_iso / Dev.CD Mar 93.iso / Development Platforms / Apple II / Essentials / Technical.Notes / GSOS / TN.GSOS.013 < prev    next >
Encoding:
Text File  |  1992-07-15  |  8.0 KB  |  180 lines  |  [TEXT/GEOL]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5. GS/OS
  6. #13: GS/OS Reference Update
  7.  
  8. Revised by: Matt Deatherage                                          May 1992
  9. Written by: Matt Deatherage & Dave Lyons                        November 1990
  10.  
  11. This Technical Note corrects and updates the Addison-Wesley Apple IIgs GS/OS
  12. Reference.   Previous versions from APDA labeled Volume 1 or 2 are obsolete,
  13. and should no longer be used.
  14.  
  15. CHANGES SINCE DECEMBER 1991:  Added new information about resource_eof and
  16. resource_blocks parameters.
  17. _____________________________________________________________________________
  18.  
  19.  
  20. CHAPTER 4, "ACCESSING GS/OS FILES"
  21.  
  22. PAGE 72:  THE SYSTEM FILE LEVEL:  HOW TO PROTECT AN OPEN FILE FROM THE
  23. APPLICATION
  24.  
  25. The class 1 SetLevel and GetLevel calls have a special option that allows you
  26. to open a file at an "internal" file level, so that it cannot be closed by an
  27. application making a Close call with reference number zero at any application
  28. level.
  29.  
  30. GetLevel and SetLevel actually accept two parameters, not just the one
  31. parameter (level) documented in Chapter 7.   The second parameter, level_mode,
  32. is a Word that controls the internal range of the file level.
  33.  
  34. Only two values for level_mode are supported.   A value of $8000 is the same
  35. as if the parameter wasn't present at all--the level calls behave just as
  36. documented in GS/OS Reference.   A value of $0000 sets a special "system" or
  37. "internal" level--all files opened with an internal level are unaffected by
  38. any non-internal level.
  39.  
  40. The steps to open a file at an internal file level are:
  41.  
  42.  1. Call GetLevel with pCount=2, level_mode=$0000.   Save the returned level.
  43.  2. Call SetLevel with pCount=2, level = $0080 and level_mode = $0000.
  44.  3. Open a file or files with a class 0 or 1 Open call, or with
  45.     OpenResourceFile (OpenResourceFile on System Software 5.0.4 and earlier
  46.     does not try to protect your resource files from being accidentally
  47.     closed by a Close(0)).
  48.  4. Call SetLevel with pCount=2, level_mode=$0000, and level = saved level.
  49.  
  50. You can use two parameters in all your level calls and set the second
  51. level_mode parameter to $8000 instead of omitting it if it will make writing
  52. your program easier.
  53.  
  54. To close your protected file, simply do a Close with the reference number.
  55. There is no need to fiddle with the file level when closing by reference
  56. number.
  57.  
  58. NDAs should close all their files at or before DeskShutDown time.
  59.  
  60.  
  61. CHAPTER 6, "WORKING WITH SYSTEM INFORMATION"
  62.  
  63. PAGE 92:  USING THE OPTIONLIST PARAMETER
  64.  
  65. The optionList parameter resembles a GS/OS output buffer in most important
  66. respects--it starts with a word indicating the size of the buffer, and each
  67. FST fills in the size of the actual data placed in the buffer in the second
  68. word.   If the buffer is too small to hold the data, the necessary size is
  69. placed in the second word and the FST returns the "buffer too small" error
  70. ($004F).
  71.  
  72. Usually, GS/OS input buffers only have one length word, because if you know
  73. how large the data is (and you do if you're the one passing it to GS/OS), you
  74. don't need another word telling you the same thing.   However, if you're
  75. trying to copy something like an optionList, you can wind up in a bit of a
  76. pickle.   Just because the buffer you've allocated is big enough to hold file
  77. system-specific information, that doesn't mean the information is necessarily
  78. present.
  79.  
  80. A good example of this problem is found in the System Software 6.0 ProDOS FST.
  81. In 6.0 and later, the ProDOS FST will take HFS Finder information (as returned
  82. by the AppleShare and HFS FSTs) in the optionList and place that information
  83. in an extended file's extended key block, so the file can be copied to and
  84. from ProDOS disks with no loss of Macintosh-specific information (such as the
  85. longer file types and creator types necessary to identify Macintosh files).
  86. The FST returns the same information (if present) in the output optionList.
  87.  
  88. However, previous versions of the ProDOS FST returned no information in the
  89. optionList.  Suppose you archived a file and stored the optionList with the
  90. file's information under 5.0, and attempt to restore the file under 6.0 using
  91. a nice, large optionList buffer.  The FST can't know whether the large buffer
  92. contains any information or not.
  93.  
  94. To remedy this problem, the second word of the optionList structure (reqSize
  95. in the figure on page 92) is now defined on input as well as output.  On
  96. input, the word must contain the actual size of the data in the optionList;
  97. the first word continues to indicate the size of the entire buffer.  If the
  98. buffer size and the actual data size are too small to make sense, any affected
  99. FSTs will ignore the input, knowing that it must be garbage.
  100.  
  101. Further details on how the ProDOS FST stores HFS Finder information can be
  102. found in ProDOS 8 Technical Note #25, "Non-Standard Storage Types."
  103.  
  104. CHAPTER 7, "GS/OS CALL REFERENCE"
  105.  
  106. PAGES 98-99:  CHANGEPATH
  107.  
  108. On page 98, the Reference states that a subdirectory may not be moved into
  109. itself or into a directory the first subdirectory already contains.   For
  110. example, you may not change /v to /v/w or /v/w to /v/w/x.   Although this is
  111. correct, the System Software 5.0.x implementations of the ProDOS FST trash
  112. your disk if you try this with ChangePath.   Do not try it on disks you want
  113. to keep.
  114.  
  115. On page 99, error $4E is described as "file not destroy-enabled."  No,
  116. ChangePath doesn't destroy the file.   The error should read "file not
  117. rename-enabled."
  118.  
  119. PAGE 120:  DINFO CHARACTERISTICS WORD
  120.  
  121. The diagram for the characteristics word in the DInfo parameters has incorrect
  122. descriptions for bits 14 and 13.   The diagram says bit 14 is set if the
  123. device is a linked device; in fact, bit 13 is set if the device is a linked
  124. device.   Bit 14 is set if the device in question has a generated driver; the
  125. bit is clear for loaded drivers.
  126.  
  127. PAGE 129:  THE CHARACTER DEVICE STATUS WORD
  128.  
  129. The diagram on the top of page 129 says that if bit 5 is set, the device is in
  130. no-wait mode.   This is incorrect.   To determine if a device is in no-wait
  131. mode, make the GetWaitStatus subcall described on page 130.
  132.  
  133. Bit 5 of the character device status word is set if there are one or more
  134. characters waiting to be read from the device.   This is an assistance for
  135. developers, since generated character drivers don't support no-wait mode.
  136.  
  137. PAGE 132:  GETFORMATOPTIONS FLAGS WORD
  138.  
  139. The diagram describing the flags word of GetFormatOptions is incorrect.   Bits
  140. 0 and 1 are actually the format type, while bits 2 and 3 are the size
  141. multiplier.   In other words, the two labels are backwards.
  142.  
  143. PAGE 142:  FLUSH
  144.  
  145. The Flush call, under System Software 5.0.3 and later (GS/OS version 3.3)
  146. accepts a maximum of two parameters.   If the second parameter is present, it
  147. is the flushType.   The flushType Word specifies the type of flush to be
  148. performed.   A flushType of $0000 is the standard flush, where all dirty
  149. blocks are written to disk.   If flushType is $8000, however, only dirty data
  150. blocks are written to disk.   Certain dirty system blocks (blocks that don't
  151. hold file data) may not be flushed in this fast flush, but volume and file
  152. integrity is maintained.
  153.  
  154. PAGE 151: GETDIRENTRY
  155. PAGE 156: GETFILEINFO
  156. PAGE 176: OPEN
  157.  
  158. Each of the above calls has optional resourceEOF and resourceBlocks paramters
  159. that are listed as "undefined" if the file has no resource fork.  In System
  160. Software 6.0 and later, these fields are guaranteed to be zero if a given file
  161. has no resource fork.
  162.  
  163.  
  164. APPENDIX A, "GS/OS PRODOS 16 CALLS"
  165.  
  166. PAGE 386:  GETDIRENTRY BUFFER DESCRIPTION INCORRECT
  167.  
  168. On page 386, nameBuffer is described as a pointer to a buffer in which GS/OS
  169. returns a Pascal string containing the name of the file or directory entry (in
  170. GetDirEntry).   This is incorrect; all versions of GetDirEntry return GS/OS
  171. (word-length) strings for the directory entry.
  172.  
  173.  
  174. Further Reference
  175. _____________________________________________________________________________
  176.  
  177.    o   GS/OS Reference
  178.    o   Apple IIgs Technical Note #71, DA Tips and Techniques
  179.    o   ProDOS 8 Technical Note #25, Non-Standard Storage Types
  180.